COMMENT ⊗   VALID 00006 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002		CAMERA  is a  program  for  moving  the COHU  and  Sierra  TV
C00006 00003		The  error flags  are  ORed  together  into one  integer  for
C00010 00004	 2000	the lookup failed for reading in the calibration files.  This
C00013 00005		The procedures declared in PREAMB.SAI are:
C00016 00006	CHNG_IRIS(INTEGER CAMNO REAL IRIS)
C00018 ENDMK
C⊗;
	CAMERA  is a  program  for  moving  the COHU  and  Sierra  TV
cameras,  as well as generating  camera transforms for them.   It can
be run by  itself for testings,  or from other  programs by means  of
message procedures.  The logical  name for message procedures is CAM.
The  program is  written so  that jobs  running under the  same upper
segment can manipulate  each camera independently  of the other;  two
routines  trying to  manipulate  the same  camera,  however, must  do
their own coordination.   When the  program is started,  it reads  in
the  calibration files  for  both cameras  and  generates an  initial
transform  for each  of  them, based  on their  current  position and
status.
	The transforms generated  by the program are 10x3  arrays and
have the following format:

	1:3,1:3	is the colineation matrix (table→tv coordinates)
	  4,1:3	is the lens center in table coordinates
	  5,1:3 is the tv coordinates where is lens  axis pierces the
		image plane
	6:8,1:3	is the inverse colineation matrix (tv→table coords.)
	  9,1	the angle of the pan head in degrees from horizontal
	  9,2	the angle of the tilt head in degrees from -X axis
	  9,3	the focus range in inches from the lens center
	 10,1	the camera number (COHU=1, Sierra=2)
	 10,2	if COHU, the lens number; otherwise  the focal length
		of the zoom lens in millimeters.
	 10,3	iris pot reading (currently valid only for camera 2)

	The following variables appear in the  upper segment to allow
access to information generated by CAMERA:

REAL ARRAY ITEMVAR ARRAY CURCAM[1:2]  is indexed by camera number and
	contains  two items whose datums are the  transforms  for the
	respective cameras in their current position.

REAL ARRAY ITEMVAR ARRAY PREDCM[1:2]  is indexed by camera number and
	contains two items whose  datums  are the transforms  for the
	respective cameras if they were in the positions indicated by
	the  transforms.   If  the prediction  procedure has not been 
	called, the items will not exist.

INTEGER ARRAY CAMERR[1:2]  is  indexed by  camera number and contains
	the error flags for the last call  of  CAMERA for that camera
	number.

INTEGER ARRAY CAMJOB[1:2]  is  indexed by  camera number and contains
	the name (in sixbit) of the job  which last executed a proce-
	dure for that camera number.

REAL ARRAY POTS[1:5,1:2] is indexed by camera number and contains pot
	readings/reference  voltage  for  pan(1),  tilt(2), focus(3), 
	zoom (4-Sierra only), and iris (5-camera 2 only for now)
	The  error flags  are  ORed  together  into one  integer  for
storage  in  the transform  and  CAMERR.   The  bits  are  decoded as
follows: (in octal)

    1	One of the servo progorams generated an error. A message  will
	be typed telling the user which camera the routines were try-
	ing to move and what the status bits from  the servo  routine
	were. The status  bits for the  COHU can be found in the doc-
	umentation for TSERVO in the hand eye  library.  Status  bits
	for the Sierra TV have not yet been documented.

    2	The update procedure did not get enough readings.  This means
	an error occured in the pot reading  code  before  3/4 of the
	readings were made.  Otherwise errors are  ignored. A message
	will be typed giving the number of readings  made,  which has
	to be 30 or more to be accepted.

    4	The pots were too noisy  when  an  update was performed.  The
	difference  between  the  minimum and maximum readings for at
	least one of the pots was above the threshold. The difference
	for the offending pot(s) will be typed out.

   10	The lens number given  to one of the routines  is outside the
	range  of the  hardware (lenses are numbers 1 through 4).  An
	error message is typed giving the routine  name and lens num-
	ber it received.  The routine exits immediately.

   20	The  pan angle  given to  one of  the routines is outside the
	range of the hardware. An error  message  is typed giving the
	routine name and the pan pot reading requested.   The routine
	exits without trying to more the camera.

   40	The tilt angle  given to  one of  the routines is outside the
	range of the hardware. Error message as for error 20.

  100	The focus range given to  one of  the routines is outside the
	range of the hardware. Error message as for error 20.

  200	the focal length given for the zoom lens is outside the range
	of the hardware. [currently not implemented]

  400	the iris position given is outside the range of the hardware

 1000	the lens changing program goofed and the lens you got was not
	the one you requested. An error message is  typed telling you
	which lens you actually got.  The  transform is  update using
	that lens.
 2000	the lookup failed for reading in the calibration files.  This
	error will be found only upon starting the program. A message
	will be  typed telling the user which data set was not found.
	The  program should not be used further until the data set is
	found.

10000	the  camera number  given to one of the programs was not 1 or
	2. The routine exits immediately. No error message is given.

20000	the A-D converter is not available for the update routine. An
	error message will be typed.

	If errors 1-4 are encountered  while updating the transforms,
the  user  is  given  the option  of  retrying  the  update from  his
terminal by  typing  the indicated  letter.   If  the update  is  not
retryed,  the  transforms are updated with whatever  input the update
routine has  us- ing the current camera position. Its accuracy is not
guaranteed.  If error 20000  was found, the update is not done  and a
message is typed telling you this.

	Below  is   a  list  of  the   message  procedures  currently
implemented. The parameters to them are:

CAMNO	is the camera number (1 or 2) LENS is the lens number, camera
	1 only (value is 1-4)

PAN	is the pan angle wanted, in  degrees. 0 is parallel to the -X
	axis  on  the  table.

TILT	is the tile angle wanted, in degrees. 0 is horizontal.

RANG	is the focus ranges wanted, in inches from the  lens center.

ZOOM	is the focal  length wanted for  the zoom lens in millimeters
	(camera  2 only)

IRIS	is the iris position in pot units (until someone has a better
	idea)

X,Y,Z	is a coordinate on, or above, the table.
	The procedures declared in PREAMB.SAI are:

CAM_INIT(INTEGER CAMNO)

	Reads in the calibration file for the selected  camera.  This
procedure need  not be called  as the program  automatically calls it
for both cameras when started.



CAM_UPDATE(INTEGER CAMNO)

	Updates  the  transform  for  the  selected  camera.     This
procedure must be  called if the  pan, tilt,   focus, zoom,   or lens
number  has been  changed for  the camera  other than  by one  of the
procedures in  this program.   All  procedures  documented here  call
this routine if the update is needed.



CHNG_LENS(INTEGER LENS)

	The turret on camera 1 is  changed to the specified lens.  If
that lens is already in position, the routine exits immediately.



MOVE_CAM(INTEGER CAMNO; REAL PAN, TILT)

	The  pan/tilt  head  for the  selected  camera  is  moved  as
specified.  Due  to the  kludgy  way calibration  is  currently done,
trying to move  the camera  to a  specific position (like  tilt to  0
degrees)  is not  too successful.   The  error may  be 5-10  degrees.
Moving 5 degrees from your current position is more accurate.



CHNG_FOCUS(INTEGER CANMO; REAL RANG)

	The selected camera is  focused as specified.  Like  the last
procedure, this one is also inaccurate, only much more so.



CHNG_ZOOM(REAL ZOOM)

	The zoom lens on camera 2 is  adjusted to the specified focal
length.
CHNG_IRIS(INTEGER CAMNO; REAL IRIS)

	The iris  on the selected  camera is  moved to the  requested
position (an error  message is typed if camera 1 is specified and the
reading out of bounds flag is returned)


CAM_CENTER(INTEGER LENS, CAMNO; REAL X, Y, Z, ZOOM)

	The selected  camera  is centered  on the  point (X,Y,Z)  and
focused  on it, using the  specified lens (camera 1)  or focal length
(camera 2).  The  lens and  focal length  given  is ignored  for  the
camera which does  not need it.  If ZOOM=0,  the current focal length
will be kept.



CAM_PRED(INTEGER LENS, CAMNO; REAL X, Y, Z, ZOOM)

	This routine is like CAM_CENTER except that the camera is not
moved.  The transform what would be correct if it were moved as
specified is generated and stored in the array PREDCM.